/*
 *  Copyright 2005 Blandware (http://www.blandware.com)
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.blandware.atleap.persistence.forum;

import com.blandware.atleap.model.core.User;
import com.blandware.atleap.model.forum.Forum;
import com.blandware.atleap.model.forum.ForumSubscription;
import com.blandware.atleap.model.forum.Topic;
import com.blandware.atleap.persistence.core.DAO;
import com.blandware.atleap.common.util.PartialCollection;
import com.blandware.atleap.common.util.QueryInfo;

import java.util.List;

/**
 * <p>DAO for forum subscriptions.</p>
 * <p><a href="ForumSubscriptionDAO.java.html"><i>View source</i></a></p>
 *
 * @author Roman Puchkovskiy <a href="mailto:roman.puchkovskiy@blandware.com">
 *         &lt;roman.puchkovskiy@blandware.com&gt;</a>
 * @version $Revision: 1.2 $ $Date: 2006/10/03 13:47:33 $
 */
public interface ForumSubscriptionDAO extends DAO {

    // ~ CRUD Methods ================================================================

    /**
     * Creates a subscription to forum or topic.
     *
     * @param forumSubscription subscription to create
     * @param forum forum to which subscription is created
     * @param topic topic to which subscription is created
     * @param user user who creates a subscription
     * @return subscription ID
     */
    public Long createForumSubscription(ForumSubscription forumSubscription,
                                        Forum forum, Topic topic, User user);

    /**
     * Retrieves a forum subscription by its ID.
     *
     * @param id ID to look up by
     * @return found subscription
     */
    public ForumSubscription retrieveForumSubscription(Long id);

    /**
     * Updates a forum subscription.
     *
     * @param forumSubscription forum subscription to update
     */
    public void updateForumSubscription(ForumSubscription forumSubscription);

    /**
     * Deletes a given forum subscription.
     *
     * @param forumSubscription what to delete
     */
    public void deleteForumSubscription(ForumSubscription forumSubscription);

    // ~ Additional methods ================================================================

    /**
     * Retrieves filtered/sorted collection of forum subscriptions.
     *
     * @param queryInfo Object that contains information about how to filter
     * and sort data
     * @return Collection of forum subscriptions
     */
    public PartialCollection listForumSubscriptions(QueryInfo queryInfo);

    /**
     * Returns whether there are already such subscriptions.
     *
     * @param forumSubscription subscription
     * @param forumId forum ID
     * @param topicId topic ID
     * @param userName user name
     * @return whether there are already such subscriptions
     */
    boolean hasDuplicates(ForumSubscription forumSubscription, Long forumId,
                          Long topicId, String userName);

    // ~ Finders ================================================================

    /**
     * Returns list of subscriptions made by particular user to given forum.
     *
     * @param forumId ID of forum
     * @param userName name of user
     * @return list of subscriptions
     */
    public List findForumSubscriptionsByForumIdAndUserName(Long forumId,
                                                           String userName);

    /**
     * Returns list of subscriptions made by particular user to given topic.
     *
     * @param topicId ID of topic
     * @param userName name of user
     * @return list of subscriptions
     */
    public List findForumSubscriptionsByTopicIdAndUserName(Long topicId,
                                                           String userName);

    /**
     * Returns a list of active subcriptions to a given forum or topic.
     *
     * @param forumId forum ID
     * @param topicId topic ID
     * @return list of active subcriptions to a given forum or topic
     */
    public List findActivatedSubscriptionsByForumIdOrTopicId(Long forumId, Long topicId);

    /**
     * Returns a list of too old non-activated forum subscriptions.
     *
     * @return list of subscriptions
     */
    public List findTimedOutForumSubscriptions();
}
